Hi there @OwainWilliams, thank you for this contribution! 👍

While we wait for one of the Core Collaborators team to have a look at your work, we wanted to let you know about that we have a checklist for some of the things we will consider during review:

• It's clear what problem this is solving, there's a connected issue or a description of what the changes do and how to test them
• The automated tests all pass (see "Checks" tab on this PR)
• The level of security for this contribution is the same or improved
• The level of performance for this contribution is the same or improved
• Avoids creating breaking changes; note that behavioral changes might also be perceived as breaking
• If this is a new feature, Umbraco HQ provided guidance on the implementation beforehand
• 💡 The contribution looks original and the contributor is presumably allowed to share it

Don't worry if you got something wrong. We like to think of a pull request as the start of a conversation, we're happy to provide guidance on improving your contribution.

If you realize that you might want to make some changes then you can do that by adding new commits to the branch you created for this work and pushing new commits. They should then automatically show up as updates to this pull request.

Thanks, from your friendly Umbraco GitHub bot 🤖 🙂

Thanks @AndyButland - really appreciate the feedback. Sorry you had to do so much tidy up on it :) Hopefully it will give me and others a good guide though on what sort of language and info should be added to the summary and descriptions

You're welcome - looks good to me now and I think is a reasonable reference also for moving forward. @kjac - do you have any thoughts at this stage please, before @OwainWilliams or anyone else looks to create further endpoint descriptions?

I have thoughts.

I think it's awesome 🤩

Good to hear! So @OwainWilliams - please let us know what your plans are for these now. Although little and often is fine, it might make sense to do another round with a few more, and then we look to merge in and take others in future PRs. I think you should also retarget this PR to v17/dev, which will mean these would come at earliest in 17.1. Targeting main they'll be for 16.4, but I don't think they will make 17.0, so that's seems a little odd. And 17.1 gives a bit more time to be able to have a reasonable collection of endpoints documented. What do you think?

I'll see if I can get another couple of smaller sections done over the coming days. Don't want to lose momentum on this. Maybe target a few that are further up the list on the swagger page. Then I'd aim to keep that going, tick off more over the coming weeks. How does that sound?

@OwainWilliams - please see what you think: #20690. I gave this a try:

After that, I think we'll have some pretty good patterns in place. Wondering if you think it's worth throwing Copilot at it to see what it can do? Could just be it follows the examples we've not got in place, and it'll be a quicker job to review and update that write from scratch.

And it seemed to work as I'd hoped after a bit of back and forth as you'll see. Now we had some good examples, we could lean on this to at least to a pretty good first draft of the descriptions. Up to you, but perhaps it'll be a fair bit quicker for you to review and suggest updates to this - either via the GitHub UI, or take a branch from this PR branch and make a PR from your fork back to it - than to write them all from scratch.

@AndyButland Looks like you had a long conversation with copilot 😄

Im a bit confused though on the next steps - did you want me to run copilot over this PR or leave this one as it is and continue working on #20690 or something else?

Happy to do what ever is needed, just wasn't 100% sure on what was being suggested.

Of course it's all up to you, but I was thinking we could:

• Approve this one and leave as is, though expect to merge it in shortly.
• Rather than start a long journey of documenting all the other API endpoints manually, use Add endpoint descriptions to all Management API controllers #20690 as a starting point for completing the job. Either you could review that PR - leaving suggestions where you think you can improve what the AI came up with, and I can apply them. Or you could use this PR's branch copilot/add-endpoint-descriptions-api as a base, create a branch in your fork and submit your changes as a PR to merge back into copilot/add-endpoint-descriptions-api. And then we merge that in, and finally Add endpoint descriptions to all Management API controllers #20690 into main.

Ah, great, thanks @AndyButland - That all makes sense. I'm happy to take a look at your PR, make adjustments to it and go from there. I don't see any point forking from your work already - seems like an unrequired extra step.

Lets close this one off and I'll take a look at your other PR and make any suggestions

No need to close this one - I would say for the endpoints it covers, it takes precedence over the other, as it established the patterns and I'd rather we have the human ones as preference! But suggest we keep it open until the other one is reviewed, and then we can have all merged in at once.

Sorry - when I said Close, I meant, not do any more to this one and I'll pick up the other PR :)